Inside Macintosh: QuickDraw GX Objects /

Chapter 4 - Colors and Color-Related Objects / Colors and Color-Related Objects Reference

Color Profile Functions / Manipulating Color Profile Object Properties

GXSetColorProfileTags

You can use the GXSetColorProfileTags function to add, remove, or replace tag objects associated with a color profile object.

void GXSetColorProfileTags(gxColorProfile target, long tagType, 
                           long index, long oldCount, 
                           long newCount, const gxTag items[]);

target

A reference to the color profile object to alter the tag list of.

tagType

The type of tag objects to replace. A value of 0 indicates that you want to replace tags of all types.

index

The (1-based) index of the first tag reference (to a tag object of the appropriate type) to replace.

oldCount

The number of tag references to replace. A value of 0 specifies that you want to insert tag references before the tag reference indicated by the index parameter, rather than replace tag references. A value of -1 (the gxSelectToEnd constant) specifies that all tag references of the requested type, starting with the tag reference indicated by the index parameter, should be replaced.

newCount

The number of tag references to insert. A value of 0 specifies that there are no tag references to insert; the existing tag references that match the criteria you specify are removed from the source color profile's tag list and disposed of.

items

An array of tag references to insert in the tag list.

DESCRIPTION

The GXSetColorProfileTags function allows you add tag references to a color profile object's tag list, to remove tag references from the list, or to replace tag references in the list with new tag references. In any of these three cases, the target parameter specifies the color profile object to be modified, the newCount parameter specifies the number of tag references to add, and the items parameter provides the new tag references.

• To add tag references, set the oldCount parameter to 0. Use the tagType and the index parameters to specify where to add the new tag references. (For example, if you specify nil for the tagType parameter and 1 for the index parameter, this function inserts the new tag references before the current tag references. If you specify a value other than nil for the tagType parameter and a value of 2 for the index parameter, the function inserts the new tag references before the second tag reference with a tag type matching the tagType parameter.)
• To remove tag references, set the newCount parameter to 0 and the items parameter to nil. You can use the index and the oldCount parameters to specify which tag references of the specified type should be removed. The index parameter indicates the first tag reference of the specified type to remove and the oldCount parameter indicates how many tag references of the specified type to remove.
• To replace tag references, use the tagType, index, and oldCount parameters
  to indicate which tag references to replace, and use the newCount and items parameters to specify the new tag references to add. If newCount is greater than oldCount, the extra tag references are placed immediately adjacent to the last tag reference replaced.

SPECIAL CONSIDERATIONS

If you attempt to modify the tag list of a color profile object used by an onscreen view device, this function posts a colorProfile_access_restricted warning.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
colorSet_is_nil
tag_is_nil
parameter_is_nil	(debugging version)
inconsistent_parameters	(debugging version)
parameter_out_of_range	(debugging version)
index_is_less_than_zero	(debugging version)
cannot_dispose_locked_tag	(debugging version)
Warnings
index_out_of_range
count_out_of_range
colorProfile_access_restricted	(debugging version)
Notices (debugging version)
tag_already_set

SEE ALSO

Tag objects are discussed in the chapter "Tag Objects" in this book.

To examine the set of tag references associated with a color profile object, use the GXGetColorProfileTags function, described in the previous section.